import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'
import Image from '@/components/Image'
import clipboardImg from './troubleshooting/clipboard.png'
import missingLocaleImg from './troubleshooting/missing-locale.png'

# 常见问题

<BadgeGroup values={[UniverTypes.GENERAL]} value={UniverTypes.GENERAL} />

## 安装相关

### 为什么我在使用 webpack 4 的项目中导入 Univer 会报错？

- webpack 4 无法正确地识别 `packages.json` 的 `exports` 字段，详见 [webpack/webpack#9509](https://github.com/webpack/webpack/issues/9509)。
你需要找到正确路径并手动引入。部分第三方依赖可能需要通过配置 `resolve.alias` 建立别名来解决。
- 在某些 webpack 4 脚手架中，默认的 babel 的配置可能不处理 node_modules 下的依赖，你可能需要手动修改 webpack 的 rules，将 `@univerjs/*` 添加到 babel-loader 的 `include` 配置中。

我们提供了一个基于 webpack 4 的[在线 demo](/playground?title=Webpack%204)，希望可以帮助你解决这个问题

### 为什么使用 `<script>` 引入 Univer UMD 包时，部分插件注册时会报错？

- 请确保你按顺序引入了插件所用到的前置依赖。
- 可在插件的文档页或插件源码的 `packages.json` 的 `peerDependencies` 字段中找到插件运行所需要的前置依赖项。

### 为什么我使用 npm 或者 yarn 安装，运行时报错找不到依赖？

这可能是因为你使用的 node 包管理工具版本较低导致， yarn 和 npm@6 不会自动安装 `packages.json` 中的 `peerDependencies`，详见 [package-json#peerdependencies](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies)。

- 你可以自行安装缺失的附属依赖项。
- 对于 npm 用户，可将 node 版本更新至 16 以上，亦或者将 npm 版本升级至 7 及以上，并留意升级行为可能对你已有项目的影响。

## 使用相关

### 复制粘贴 / 剪贴板

#### 为什么在 Firefox 里无法使用右键中菜单的粘贴？

Firefox 尚不支持 `clipboard.readText()`，详见 [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/readText)，在这种情况下，Univer 只能从粘贴事件中获取剪贴板内容，因此只能支持快捷键粘贴。

#### 我使用 Chrome 浏览器，但是无法使用右键中菜单的粘贴？

首先请确保你的浏览器版本在 66 以上，然后请确保你的网站是通过 HTTPS 协议访问的，由于 Chrome 的安全策略，只有在 HTTPS 协议下才能使用 `clipboard` API。

#### 为什么我无法进行复制粘贴？

在 Chrome 和 Safari 等支持 `clipboard.readText()` 的浏览器中，Univer 会直接尝试获取剪贴板内容，请确保操作的用户授予了 Univer 浏览器的剪贴板权限。

<Image src={clipboardImg} alt="Authorize Clipboard" width={500} />

## 开发相关

### 为什么我的菜单项中没有显示正确的语言？

这是因为你遗漏了对应的语言包，你需要在初始化 Univer 时传入对应的语言包，详情请参考各个功能项中国际化相关的文档。

<Image src={missingLocaleImg} alt="Missing Locale" width={300} />

### 📊 如何实时获取单元格编辑器内的数据？

Univer Sheet 的单元格编辑器本质上就是 Univer Doc 的编辑器，因此你可以通过 Facade API 获取当前激活的 Univer Doc 编辑器内的 snapshot 数据。

```typescript
univerAPI.onCommandExecuted((command) => {
  const { id } = command;
  if (id === 'doc.command.insert-text' || id === 'doc.command.delete-text') {
    const doc = univerAPI.getActiveDocument();
    if (doc) {
      const snapshot = doc.getSnapshot();
      console.log(snapshot.body?.dataStream);
    }
  }
});
```

参考：https://github.com/dream-num/univer/discussions/2261

### 📊 单元格编辑器聚焦时点击外部按钮触发事件，获取的 snapshot 中未包含该聚焦单元格的数据

单元格的数据会在失焦时同步到 snapshot 中，因此你应当在获取 snapshot 数据前先对单元格进行失焦操作。

```typescript
import { DeviceInputEventType } from '@univerjs/engine-render';
import { FUniver } from '@univerjs/facade';

const univerAPI = FUniver.newAPI(univer);

$btn.addEventListener('click', () => {
  univerAPI.executeCommand('sheet.operation.set-cell-edit-visible', {
    visible: false,
    _eventType: DeviceInputEventType.PointerUp,
  });
});
```

参考：https://github.com/dream-num/univer/issues/1314

## 集成相关

### 使用 React

首先请确保你的 React 版本在 16.9 以上，因为 Univer 的 UI 层依赖 React，并且使用了 React Hooks。

此外，Univer 依赖的 DI 库 `@wendellhu/redi` 存在一个已知问题，即暂时不支持 React 的 StrictMode，通过移除 StrictMode 可以解决这个问题。

```diff
- <React.StrictMode>
  <App />
- </React.StrictMode>
```

### 使用 Angular

使用 Angular CLI 默认创建的项目模板引入 Univer 前需要确保是否在 `tsconfig.json` 中配置了 `"skipLibCheck": true`：

```diff
{
  "compilerOptions": {
+    "skipLibCheck": true
  }
}
```

## 故障排查

### Error: [ThemeService]: current theme is not set!

```
Error: [ThemeService]: current theme is not set!
```

出现该错误的原因是因为你在使用 Univer 时没有设置主题。你需要通过以下方式来设置主题：

```typescript {2}
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
      [LocaleType.ZH_CN]: zhCN,
  },
});
```

### Error: [LocaleService]: Locale not initialized

```
Error: [LocaleService]: Locale not initialized
```

出现该错误的原因是因为你在使用 Univer 时没有初始化语言环境。你需要通过以下方式来初始化语言环境：

```typescript {3-6}
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
      [LocaleType.ZH_CN]: zhCN,
  },
});
```